PhAST - Aplicaciones¶

Aplicaciones¶

Las Apps son pequeñas aplicaciones en script que dependen de una aplicación más grande, nuestra plataforma PhAST, que la ejecuta de manera controlada, a través de reglas establecidas.

Observando el macro diagrama presente en la documentación de la arquitectura de la plataforma Phoebus para terminales POS, notamos algunas características interesantes sobre las aplicaciones:

Lenguaje: Las aplicaciones están escritas en Java Script Lite según el lenguaje WMLS, y usando una API de extensión.

Ejecución: Las aplicaciones son ejecutadas por la máquina virtual Phoebus (PhVM).

Competición: PhAST administra una o más aplicaciones existentes en la terminal.

Definiciones de la aplicación¶

Las Apps se registran con PhAST a través de un archivo con extensión INI que tiene parámetros relacionados con las Apps. Aquí hay un ejemplo de un archivo INI:

applet.ini

[Applet]
TESTE=package: //teste/teste.wmlsc

[TESTE]
teste.limite.transacoes=100

Dónde:

[APPLET] - Define el PhScript de la aplicación principal. Este PhScript sirve como Entry Point del aplicación.
[TESTE] - Define los parámetros de entrada para la aplicación que se define. En este punto se pueden agregar varios parámetros. Todos definido por la App.

Configuraciones locales¶

El PhAST reserva un área en su propia configuración locales para cada aplicación mantener sus respectivas configuraciones locales.

Las configuraciones locales son estructuras PhType.STRUCT asociadas con cada aplicación. Donde cada una de estas aplicaciones guarda libremente los datos en sus respectivas estructuras.

Configuraciones de inicialización¶

El PhAST también hace posible que cada aplicación agregue información personalizable a la solicitud de inicialización de la terminal junto al PhAST Host.

No es muy común que las aplicaciones contengan dicha información. Actualmente, solo las aplicaciones residentes en Phoebus utilizan estas funciones.

Servicios¶

Existe un concepto creado en PhAST para su uso en aplicaciones, que es el de servicios públicos. Con este concepto, cada aplicación publica su lista de servicios que quiere ofrecer a otras aplicaciones al PhAST.

Por ejemplo, una aplicación de pago puede publica servicios relacionados con el pago para que otras aplicaciones los utilicen, sin necesidad de conocer la aplicación que los publicó.

Más detalles, consulte la documentación de la API de servicios PhAST.

Funciones de integración¶

El PhAST define puntos de integración con la aplicación. Estos puntos son para que la aplicación se inicie junto con PhAST, informar incidencias en la terminal, entre otros. Los puntos son los siguientes:

init
main
term
resetInitCfg
resetSpecCfg
setup
outset
showidleScreen
onCheckInstallation
publicServices
OnAcceptTCPConnection
addAppletToIdleScreen
start
refreshIdleScreen
onIdle
onIdleRefresh
onCheckInstallation
unlock
onError
getDataFileNames
getConfigFileNames
onEventStart
onEventFinish
onLogin
onLogout
onShiftOpen
onShiftClose
onChipCardDetected
onMagCardDetected
onManualCardDetected
notifyAppletInstallation
onAddFieldsUpdate
onUninstall

Todo las funciones de integración presentadas aquí, cuando se utilizan, deben declararse como extern.

init(Applet)¶

Esta función se llama la administración de aplicaciones PhAST en el proceso de inicialización de la terminal POS. Es importante tener en cuenta que PhAST primero realiza su propio proceso de inicialización y luego llama a las inicializaciones de las aplicaciones registradas en el POS, obedeciendo el orden de definición de las aplicaciones.

Parámetros¶
+ **Applet** - Es un mapa relacionado con los parámetros presentes en el archivo .INI de los respectivos Applet.
Devuelve¶
Devuelve un booleano que indica:
+ **true** - Cuando funcionó todo el proceso de inicio de la aplicación
false - Cuando hubo alguna falla

Es importante mencionar que cuando una aplicación falla en su proceso de inicialización, será deshabilitada por PhAST y no permite su ejecución.

main()¶

Estan función se define si una aplicación quiere asumir completamente el flujo de ejecución de PhAST. Es extremadamente importante que solo una aplicación debe tener lo main, de lo contrario, PhAST ejecutará secuencialmente la función main de todas las aplicaciones activas.

Por lo general, las aplicaciones no necesitan asumir esa responsabilidad, así que no es necesario que contenga la función main en su PhScript. Con eso, la aplicación se ejecuta a través del flujo natural de PhAST.

Parámetros¶
+ **Ninguno**
Devuelve¶
Devuelve un booleano que indica:
+ **true** - Posee y ejecuta el flujo principal
false - posee, pero no ha ejecutado el flujo principal

El mejor tratamiento para esta cuestión de que la App quiera asumir o no el flujo principal, es el siguiente:

Quiero tomar el control: Defina la función main en su PhScript y en está se vuelve true.

No quiero tomar el control: No defina la función main en su PhScript.

term()¶

Esta función se llama cuando la aplicación se cierra junto con PhAST.

Parámetros¶
+ **Ninguno**
Devuelve¶
+ **Ninguno**

Antes de que PhAST se apague, esté cierra todas las aplicaciones activas desde la terminal.

resetInitCfg(dataList)¶

Esta función se llama cuando la terminal se configura por primera vez o cuando se ha eliminado toda la configuración de la terminal. Estos son los ajustes necesarios para enviar al HOST al instalar la terminal.

Parámetros¶
+ **dataList** - PhType.STRUCT lo cuál será el contenido de la configuración de la aplicación al instalar la terminal.
Devuelve¶
Devuelve un booleano que indica:
+ **true** - Configuración exitosa
false - Falla en la configuración

Por lo general, las aplicaciones no residentes no necesitan mandar configuraciones específicas a HOST PhAST.

resetSpecCfg(dataList)¶

Esta función se llama cuando la terminal se configura por primera vez o cuando se ha eliminado toda la configuración de la terminal. Estas son configuraciones locales de la terminal que la aplicación quiere almacenar.

Parámetros¶
+ **dataList** - PhType.STRUCT lo cuál será el contenido de la configuración local de la aplicación.
Devuelve¶
Devuelve un booleano que indica:
+ **true** - Configuración exitosa
false - Falla la configuración

setup()¶

Función llamada después de la configuración exitosa de la terminal POS en su proceso de instalación. A través de esta función de integración, la aplicación también tiene la oportunidad de capturar información importante para ella.

Parámetros¶
+ **Ninguno**
Devuelve¶
+ **Ninguno**

outset()¶

Función llamada por PhAST después de que completa todo el proceso de inicialización. Es una notificación posterior, en comparación con la función init, en el inicio de la aplicación.

Parámetros¶
+ **Ninguno**
Devuelve¶
Devuelve un booleano que indica:
+ **true** - En caso de notificación exitosa
false - En caso de falla

showidleScreen(list)¶

Función llamada por PhAST cada vez que se muestra la pantalla IDLE del POS . Esto asegura que siempre que el POS realice una transacción o ejecute un evento, cuando regrese a la pantalla IDLE, se notificarán todas las aplicaciones activas.

Parámetros¶
+ **list** - PhList que contiene dos elementos:
+ Mensaje - Mensaje que se muestra en la pantalla IDLE, normalmente mensaje "Insertar o deslizar la tarjeta"
+ contador (OBSOLETO)
Devuelve¶
**Ninguno**

onCheckInstallation(inicUpdated)¶

Función llamada por PhAST siempre que se produce una inicialización. Un detalle importante es que si ocurre un error, la función no se llama. De esta manera, podemos garantizar que la función solo se llame al final de una inicialización completada con éxito.

Parámetros¶
+ **inicUpdated** - Indica si la inicialización cambio alguna configuración del POS.
Devuelve¶
Devuelve un booleano que indica:
+ **true** - En caso de notificación exitosa
false - En caso de falla

Una nota importante es que si alguna aplicación devuelve false en esta función, la terminal comprenderá que es necesario volver a realizar toda la inicialización.

publicServices()¶

Función llamada por PhAST para comprobar si la aplicación quiere publicar servicios, que contiene funciones útiles para cualquier aplicación, pero preservando quien está ejecutando.

Parámetros¶
+ **Ninguno**
Devuelve¶
**Ninguno**
Observación:¶
+ **Registro**: El registro de servicios se realiza a través de la función *register* del módulo *package://phast#Applet/service.wmlsc*
Ejecución: La ejecución de los servicios se realiza a través de la función execute del módulo package://phast#Applet/service.wmlsc

Más detalles, consulte la documentación de la API de servicios PhAST.

OnAcceptTCPConnection(socket)¶

Función llamada por phast para notificar la llegada de una conexión de socket a través del puerto que la misma aplicación solicitó listen.

Parámetros¶
+ **socket** - Socket que se puede manipular con Stream
Devuelve¶
**Ninguno**
Observación¶
+ **Servidor**: Una aplicación puede solicitar que listen un puerto a través del parámetro "port" definido en su conjunto de definiciones.
+ **Desconexión**: Después de la función Devuelve *OnAcceptTCPConnection* para PhAST, desconectará el socket establecido.

addAppletToIdleScreen()¶

Permite que la aplicación agregue un botón funcional al menú de aplicaciones de la pantalla IDLE del PhAST.

Parámetros¶

Ninguno

Devuelve¶

return - invalid o PHList - con sublistas que contiene el formato de [LABEL, SHORTCUTKEY, SCRIPT]. Desvulve una lista (PhList) con la definición del botón, como se detalla a continuación:

Label - Label del botón;

Atajo - Atajo de teclado para el botón;

Función - Ruta completa de la función PhScript que se ejecutará cuando se haga clic en el botón. Esta función no puede tener parámetros;

Observación¶

La función que recibe el evento de activación del botón, además de necesitar ser definida como externa, no puede tener Parámetros.

El valor entero que hace referencia al ATAJO insertado en la lista no se puede repetir entre las otras aplicaciones en ejecución, si hay un conflicto, este entero debe cambiarse por otro valor disponible.

La pantalla principal admite hasta seis (6) botones.

Ejemplo¶
extern function addAppletToIdleScreen()
{
  var result  = [];
  var bt = ["Teste", 14, "package://hello/hello.wmlsc#start"];
  PhList.add(result, bt);
  return result;
}

start()¶

Función de entrada si la aplicación se utiliza junto con el módulo PayStore. Si está instalado, se ejecuta haciendo clic en la tienda de aplicaciones.

Parámetros¶
**Ninguno**
Devuelve¶
**Ninguno**
Observación¶
**Ninguno**

refreshIdleScreen()¶

Función llamada en el primer draw de la pantalla Idle, junto con las otras aplicaciones en la VM, siguiendo el orden de inicialización.

Parámetros¶
+ **progress:Integer** - progreso interno con el uso conjunto a PHDM
+ **title:String**     - @ref showIdleScreen
+ **msg1:String**      - @ref showIdleScreen
+ **msg2:String**      - @ref showIdleScreen
Devuelve¶
**Ninguno**
Observación¶
**Ninguno**

onIdle()¶

Función llamada a final del primer draw de la pantalla Idle, junto con las otras aplicaciones en la VM, siguiendo el orden de inicialización.

Parámetros¶
**Ninguno**
Devuelve¶
**Ninguno**
Observación¶
**Ninguno**

onIdleRefresh()¶

Función llamada al final de cada refresh de la pantalla idle, junto con las otras aplicaciones en la VM, siguiendo el orden de inicialización.

Parámetros¶
**Ninguno**
Devuelve¶
**Ninguno**
Observación¶
**Ninguno**

onCheckInstallation()¶

Función llamada al final del inicio de la aplicación con el servidor, junto con otras aplicaciones en la VM, siguiendo el orden de inicialización.

Parámetros¶
+ **inicUpdated:Boolean ** - Indicando éxito en la extracción de archivos de respuesta de inicialización
Devuelve¶
**true ou false**
Observación¶
**Ninguno**

unlock()¶

Función llamada cuando el estado de la aplicación está en #ST_LOCKED, junto con las otras aplicaciones en la VM, siguiendo el orden de inicialización.

Parámetros¶
**Ninguno**
Devuelve¶
**Ninguno**
Observación¶
**Ninguno**

onError()¶

Función que recibe un código de error de VM después de mostrar la pantalla de error

Parámetros¶
+ **code:Integer ** - pasado el código de error.
Devuelve¶
**true ou false**
Observación¶
**Ninguno**

getDataFileNames()¶

...

Parámetros¶
+ **list**
Devuelve¶
**Ninguno**
Observación¶
**Ninguno**

getConfigFileNames()¶

...

Parámetros¶
+ **list**
Devuelve¶
**Ninguno**
Observación¶
**Ninguno**

onEventStart()¶

...

Parámetros¶
**type**
Devuelve¶
**Ninguno**
Observación¶
**Ninguno**

onEventFinish()¶

...

Parámetros¶
+ **type**
+ **result**
Devuelve¶
**Ninguno**
Observación¶
**Ninguno**

...

Parámetros¶
+ **login**
+ **online**
Devuelve¶
**Ninguno**
Observación¶
**Ninguno**

onLogout()¶

...

Parámetros¶
**Ninguno**
Devuelve¶
**Ninguno**
Observación¶
**Ninguno**

onShiftOpen()¶

...

Parámetros¶
+ **userId**
+ **shiftId**
Devuelve¶
**Ninguno**
Observación¶
**Ninguno**

onShiftClose()¶

...

Parámetros¶
+ **userId**
+ **shiftId**
+ **date**
Devuelve¶
**Ninguno**
Observación¶
**Ninguno**

onChipCardDetected(transactionId, appType)¶

Función que se realizará cuando se inserte una tarjeta con chip en la terminal.

Parámetros¶
+ **transactionId** - Identificador de operación.
+ **appType**       - Tipo de operación seleccionada (Débito o Crédito)
Devuelve¶
+ **true** - Informe a Phast que la responsabilidad de la aplicación que devuelve es responsable de manejar este evento, por lo que Phast no mostrará el menú de pago predeterminado.
false - Indica que Phast es responsable de manejar el evento, que seguirá el comportamiento predeterminado.

Observación¶
**Ninguno**

onMagCardDetected(transactionId)¶

Función que se realiza al deslizar una tarjeta con una banda magnética.

Parámetros¶
+ **transactionId** - Identificador de transacción.
Devuelve¶
+ **true** - Informa a Phast que la responsabilidad es de la aplicación que devolvio el manejo de este evento, por lo que Phast no mostrará el menú de pago predeterminado.
false - Indica que Phast es responsable de manejar el evento, que seguirá el comportamiento predeterminado.

Observación¶
**Ninguno**

onManualCardDetected(transactionId)¶

Función que se realiza al ingresar el número de tarjeta manualmente.

Parámetros¶
+ **transactionId** - Identificador de transacción.
Devuelve¶
**true o false**
Observación¶
**Ninguno**

notifyAppletInstallation(app)¶

Notificar a todo las aplicaciones instaladas cuando se complete la instalación de una nueva aplicación.

Parámetros¶

+ **app** - PhList que contiene datos de la aplicación:

          [0] - String packageName, nombre del paquete de la aplicación.
          [1] - String appName, nombre de la aplicación.
          [2] - String appVersion, version de aplicacion.
          [3] - String mainScript, ruta de la secuencia de comandos de la aplicación principal.
          [4] - String appType, Tipo de aplicación (App o skin).

Devuelve¶

**Ninguno**

Observación¶

**Ninguno**

onAddFieldsUpdate()¶

Notifica a todas las aplicaciones instaladas cuando se actualizan campos adicionales.

Parámetros¶
**Ninguno**
Devuelve¶
**Ninguno**
Observación¶
**Ninguno**

onUninstall()¶

Notifica a todas las aplicaciones instaladas que se ha desinstalado una aplicación.

Parámetros¶
**Ninguno**
Devuelve¶
**Ninguno**
Observación¶
**Ninguno**